Visual Basic Toolbox/Visual Basic Toolbox (P.I.E.)(1996).ISO/lang_ext/vbawk/vb-awk.doc

Text File | 1994-08-15 | 25.8 KB | 589 lines

                            INTRODUCTION:


WHAT IS VB-AWK?

VB-AWK is a productivity tool which attempts to simulate the power and
features of the AWK programming language in a Windows environment.
VB-AWK creates native Windows apps using the Visual Basic development
environment, with many of the powerful features and conveniences of AWK.

VB-AWK was created by a professional consultant with 14 years
programming experience and expertise in user-interface design. VB-AWK is
copyrighted software which costs 25$.  This fee is required from anyone
who keeps it beyond a 30-day trial period.

Those of you who know what AWK is may skip the following section.


WHAT IS AWK?

AWK is an interpreted, C-like language, most often found on UNIX
platforms, which is highly specialized for the creation of filter
programs.  A filter is a program which uses one or more files for input,
performs an action on those files, and writes them out again.  Filter
programs tend to be very useful as utilities.

Virtually any text-processing program may be written in AWK more easily
than (arguably) any other language.  AWK performs all the busywork of
opening, reading, writing, and closing, the files for you, leaving you
free to concentrate on the details of the task to be performed.  AWK is
also very useful for the creation of flat-file databases and almost any
other program whose primary purpose is to manipulate files.


WHAT ARE THE ADVANTAGES OF USING VB-AWK?

1. PRODUCTIVITY:  You can create very powerful filter programs extremely
easily.  A program to count the number of lines in a file, for instance,
requires writing exactly one line of code, and still contains a friendly
and  powerful GUI user interface. (See the sample program LINECNT).

2. POWER: All programs created with VB-AWK inherit a powerful and
flexible GUI interface, as well as a powerful command-line interface
that's very useful when specified from a Windows program item property.
Additionally, since VB-AWK programs are created from within the Visual
Basic environment, and the "innards" of VB-AWK are completely
accessible, any program that can be created in Visual Basic can also be
created using VB-AWK.


WHEN WOULD I WANT TO USE VB-AWK?

The great thing about VB-AWK is that it makes the creation of
quick-and-dirty utility programs so easy that it becomes time-effective
to write such programs.   For instance, if you need to perform a
complex editing operation on a large number of files, it would be far
easier to write a VB-AWK program to do it than to either do it by hand
or write an editor macro.  It wouldn't be terribly difficult to write a
straight VB program to do it either, but it wouldn't be worth doing if
it would take an hour to write a program that saves 30 minutes of
editing. It would be very worthwhile to spend 5 minutes writing such a
program, however.  That's where VB-AWK comes in.

Also, VB-AWK provides a very useful file-processing framework for any
VB program.  VB-AWK will open an arbitrary number of files for you,
feed you each line from the files, write each line back out and close
the file, all without any programming on your part.  Starting out with
VB-AWK will save several hours of programming time on virtually any
program which performs file i/o, even if file processing is not that
program's main purpose.  For instance, many programs will initially open
a configuration file and read setup information.  VB-AWK can do that for
you.


WHAT BEHAVIORS DO ALL VB-AWK PROGRAMS SHARE?

1. All VB-AWK-generated programs have a specialized file-open dialog
that allows selection of multiple files for the program to operate on.
This dialog appears initially when you run any VB-AWK-created program.
This dialog also has the option of expanding subdirectories, to perform
operations on all files below a given directory.

2. All VB-AWK-generated programs also have a command-line interface
that allows selection of multiple files for the program to operate on,
via standard DOS file specifications with wildcards.  Additionally, a
list file may be specified containing a list of files to execute the
program on.  If any of these command-line options are used to specify
files, the  file-open dialog will automatically be suppressed.

3. All VB-AWK-generated programs will open every file specified, read
the contents of the file in either binary or text mode, and pass it to
user-written code for  processing, a line at a time (or a chunk at a
time for binary files).

4. All VB-AWK-generated programs display a status box as they are
processing files.  The status box displays each file's name as it is
being opened.  The status box also will display any errors encountered
as the file is being processed, and a message when all processing is
finished.  The status box can be easily suppressed, and can also be
accessed from user code.  Additionally, it allows you to write the
contents of the box out to a file.


                    VB-AWK PROGRAMMER'S GUIDE


HOW TO CREATE A PROGRAM WITH VB-AWK:

1. Create a directory for the program, say \MYPROG.

2. Unzip VB-AWK.ZIP into that directory.  It will create a Visual Basic
project there called VB_AWK.MAK.

3. Fire up Visual Basic and open the VB-AWK.MAK project.  NOTE:
The project will expect CMDIALOG.VBX to exist in the Windows
system directory on drive C:, C:\WINDOWS\SYSTEM\CMDIALOG.VBX.

4. Implement your program by adding code to the routines in
USERCODE.BAS. See the following section for a description of those
routines.  Many simple programs will not need any other forms or code.
If yours does, you may  create and use any other forms, add modules of
your own, etc.   VB-AWK programs are normal Visual Basic programs in
every way.

5. Debug and test your program from within the VB environment just like
any other VB program, and make an EXE file when it's ready.  The default
name for the EXE file will be VB-AWK.EXE; you'll probably want to rename
it.

6. You're done!

Note that VB-AWK makes use of common dialogs and requires two files,
CMDIALOG.VBX and COMMDLG.DLL.  These are not part of VB-AWK and are
supplied with Visual Basic.  Also note that VB-AWK was developed under
VB 3.0.  It would probably run under 2.0 with little or no tweaking.



WHERE YOU PUT YOUR CODE:

All the code for a VB-AWK program is put in the module USERCODE.BAS.
There are 5 routines there which are stubbed out.  These routines are
called by VB-AWK under various circumstances described in the next
paragraph.  Writing a VB-AWK  program consists of fleshing out these
routines, none of which are mandatory.   (A VB-AWK program with no
USERCODE routines fleshed out will read files and write them out again
with no modification, listing all the files it processes in the
status box).

The USERCODE routines are as follows:

    Function DoALine( TheLine As String) As Integer

        This is the workhorse routine and the only one that many
        programs will ever need to flesh out.  DoALine is called
        once for every line in every file being processed.
        'TheLine' is that line.  Your code can do anything it wants
        to TheLine.  VB-AWK will write TheLine back to the file with
        your modifications.

        If you wish to skip processing this line completely, set DoALine
        = False, and the line will never be written out.  The stub sets
        it to True which is the typical usage.

        Note that VB-AWK opens the input file as #1, and the output
        file as #2.  If you wish to write out more than one line of
        output for each line of input, you may do so by printing to
        #2.

    Function BeforeAFile As Integer

        This routine is called once for each file being processed.  It
        is called before the file is opened and any lines are
        read.  Place initialization code here that is required once per
        file.  Many programs won't need anything here.

        BeforeAFile normally returns True.  If your code determines that
        there is some reason to skip processing this file, you can set
        BeforeAFile to False and the file will not be processed.

    Sub AfterAFile

        This routine is called once for each file being processed.  It
        is called after a file is completely finished and
        closed.  If there's any cleanup you need to perform after a
        file is processed, put it here.

    Function BeforeAllFiles

        This routine is called only once, before any files are opened or
        processed in any way.  This is a place to put initialization
        code, if you have any.  This is also the usual place to set
        VB-AWK control variables such as STATUSFILE or APPNAME (see
        below).  It normally returns True; by making it
        return False, you can abort the program before it processes any
        files at all.

    Sub AfterAllFiles

        This routine is called only once, after all files are processed
        and closed.  This is where you might want to put a "Finished"
        message if you don't like the built-in one.



BUILT-IN VARIABLES:

VB-AWK has numerous built-in variables.  Some of them are read-only and
contain valuable information.  Others may be set by the user code and
control certain aspects of VB-AWK's operation.

    Dim FILENAME As String      'read-only

        This variable contains the fully-qualified name of the file
        currently being processed.

    Dim FNR As Long             'read-only

        (F)ile (N)umber of (R)ecords.  This contains the number of
        records that have been read in so far for the current file.
        In text mode one line is considered a record; in binary mode,
        one chunk.

    Dim NR As Long              'read-only

        (N)umber of (R)ecords.  This contains the total number of
        records read in so far, over all files processed.

    Dim NF As Integer           'read-only

        (N)umber of (F)iles.  This contains the total number of
        files processed so far.

    Dim STATUSBOX As Integer    'control variable

        If set to True (the default), indicates that the program makes
        use of the VB-AWK status box.   If set to False (usually in
        BeforeAllFiles), the status box will not appear and status
        messages are thrown into the bit bucket of life.  Setting
        STATUSBOX = False after it has already appeared will not make
        the box disappear, but will disable messages to it, just like
        setting STATUSMESSAGES to False.

    Dim STATUSFILE As Integer   'control variable

        If set to True, then WriteToStatus will write to a file called
        VB-AWK.LOG in the current directory.  STATUSBOX and STATUSFILE
        are compatible; if they are both set to TRUE, messages will be
        sent to the file and echoed to the status box too.  The default
        value is False.

    Dim STATUSMESSAGES As Integer

        If set to True (the default) indicates that the program wishes to
        make use of the standard VB-AWK status messages.  These consist of
        a message that says "Processing file nnn..." when each file is
        opened for processing, which has the string "finished!" appended
        to it when processing is finished, and a message "Finished
        with all files!" at the end.

    Dim BINARYMODE As Integer   'control variable

        When BINARYMODE is False (the default), files are read in text
        mode.  Each time DoALine is called, it is passed the current
        line of the file, as delineated by carriage-return/line feed.
        The terminating cr/lf is not passed.

        If BINARYMODE is set to True (typically in the BeforeAllFiles
        routine), DoALine is passed a chunk of bytes from the file.
        The length of the chunk is given by RECLEN (see below).  All
        characters, including control characters and cr/lf, are in
        the chunk.

    Dim RECLEN As Long          'control variable

        Holds record length for binary files, which will typically be
        set in BeforeAllFiles or BeforeAFile. It is ignored for text
        files.

    Dim APPNAME As String       'control variable

        May be set to the name of your application, whatever you wish
        it to be known as.  This will customize the captions in the
        VB-AWK file-open dialog and status box.

    Dim COMPAREMODE As Integer  'control variable

        If COMPAREMODE is set to COMPARE_CASESENSITIVE (value 0), then
        the 'gsub' subroutine and any other VB-AWK string processing
        routines will be case-sensitive.  If set to
        COMPARE_CASEINSENSITIVE, then all such routines will be case
        insensitive.  The default is COMPARE_CASEINSENSITIVE.


SYSTEM ROUTINES:

You can access the status box through the following routines:

    Subroutine WriteToStatus( TheStr As String)

        Appends a line consisting of 'TheStr' to the status message box.
        If STATUSBOX is set to FALSE, this routine will also do nothing.

    Subroutine AppendToStatus( TheStr As String)

        Appends a string, 'TheStr', to the current line on the status
        box.  If STATUSBOX is set to FALSE, this routine will do
        nothing.

The status box has a capacity of about 64K worth of messages; if you
attempt to write more than that, a message box will inform you that
memory has overflowed and the list box will be cleared of messages.
If there's much chance of that happening, you're better off setting
STATUSBOX to False and STATUSFILE to True, sending all messages to
VB-AWK.LOG.


UTILITY ROUTINES:

VB-AWK contains a number of "the routines that Microsoft forgot", as
well as some routines borrowed from AWK.   These routines can save many
hours of programming time.  They are found in a file called UTILS.BAS,
which at present contains the following routines:

    Function gsub (TheString As String, SearchFor As String,
                   Subst As String) As Integer

        This is an AWK utility which performs a global substitutions
        within a text string.  It will look in TheString for occurrences
        of SearchFor, and replace each occurrence with Subst.  It
        returns the number of replacements actually made.

    Function StrTok (ByVal TokenStr As String,
                     Delimiters As String) As String

        This is borrowed from the 'C' language function by the same name
        and behaves very similarly. StrTok parses a string, TokenStr,
        which is treated like it consists of tokens separated by
        delimiters. Each Time you call StrTok, it returns the next token
        in the string.

        The first time you call it, TokenStr should be the string to
        parse, and Delimiters is the string containing characters that
        delimit the tokens. For instance, if the tokens are separated by
        either commas or blanks, Delimiters should be the following:
        " ,"

        On succeeding calls to StrTok, TokenStr should be a zero- length
        string ("").  StrTok will remember what TokenStr was. However,
        Delimiters can be anything you want it to be; thus, you can look
        for different delimiters on succeeding calls.

        StrTok returns "" when it can find no more tokens.


    Sub Substitute (TheText$, StartLoc%, TheLen%, Subst$)

        This routine replaces part of one string with another.  It
        replaces the part of TheText$ which starts at StartLoc% and
        has length of TheLen%, and replaces it with Subst$.

        This routine appears to have the same behavior as using Mid$ on
        the left side of an assignment, but Mid$ will truncate the
        substitution string if it is longer than what it is replacing,
        while this routine does not.

    Function ReverseString( TheStr As String) As String

        This function returns a string which contains all the characters
        of TheStr in reverse order.


    Sub SplitFilePath (ByVal ThePath$, TheDrive$, TheDirs$, TheFile$,
                       TheExtension$)

        This routine accepts a file pathname as ThePath$, and splits it
        into its component parts.  If ThePath$ contained a drive
        specifier, it returns it in TheDrive$; if it contained directory
        specifiers they are returned in TheDirs$; it returns the
        file name, minus extension, in TheFile$; and it returns the
        extension, if any, in TheExtension$.  If ThePath$ is missing
        any of these qualifiers, the corresponding string is set to "".

    Function FileExists (Filename As String) As Integer

        Returns TRUE if the given filename exists, otherwise
        returns FALSE.


COMMAND-LINE INTERFACE:

The command-line interface for a VB-AWK-created program called MYPROG is
as follows:

    MYPROG  filespec

        This will launch MYPROG so it will process all files specified
        by 'filespec', which can contain any valid DOS wildcards.  A
        planned enhancement is to allow more than one filespec on the
        command line.  You can work around the current limitation by
        using a listfile as described in the next paragraph.


    MYPROG  @listfile

        This will launch MYPROG so it operates on all the files
        specified in the listfile named  'listfile'.  'listfile'
        should contain a list of files (or filespecs), left justified,
        with each filespec on its own line.

    MYPROG

        Specifying no command-line parameter will cause the file-open
        dialog to appear initially, allowing the user to pick whatever
        files he or she wants.

Note that if a command line is specified, the file-open dialog will be
suppressed.


                            SAMPLE PROGRAMS:


A number of useful utilities have been written using VB-AWK to
demonstrate its capabilities.  The simplest one, LINECNT, is supplied as
an executable so that you may easily see the user interface VB-AWK
supplies.   The others are source code only and can easily be built by
following the directions for creating a VB-AWK app, then adding the
appropriate files to the project.   Each of  these utilities exhibits all
the standard VB-AWK behaviors described previously.



    LINECNT (Line Count)

        Counts the number of lines in each file chosen and displays the
        line count of each.  This requires writing exactly one line of
        code.  To make it display the grand sum over all files would
        require exactly one more line of code; as the textbooks say,
        we'll leave it up to the reader for an exercise to determine
        what that line is and where it goes.

        NOTE: LINECNT.EXE, like all VB 3.0 executables, requires
        VBRUN300.DLL to be in your Windows directory or windows/system.
        This is not included in VB-AWK but is part of VB 3.0.

        ANOTHER NOTE: LINECNT.EXE opens files in text mode (i.e.,
        BINARYMODE = False).   Don't run it on binary files such as
        EXE files. It will truncate them if they contain an EOF
        character.

        HOW TO BUILD IT:  The source code is in the file LINECNT.USR.
        Unzip VB-AWK.ZIP, copy LINECNT.USR on top of USERCODE.BAS, and
        build the executable from VB.

    ENTAB

        Substitutes tabs for strings of blanks.  Allows
        custom-specifying the desired tab stops or specifying fixed
        tabs.  (Note: ENTAB expects there will be no tabs in the
        file already.   If this is not the case, you can run DETAB on
        it first and then run ENTAB).

        HOW TO BUILD IT:  The source code is in ENTAB.USR, and one form
        that's required is in SETTABST.FRM.  Unzip VB-AWK.ZIP, copy
        ENTAB.USR on top of USERCODE.BAS, then from VB, add SETTABST.FRM
        to the project and build your executable.

    DETAB

        Expands tabs in a file to blanks.  Allows custom-specifying the
        desired tab stops or specifying fixed tabs.

        HOW TO BUILD IT:  The source is in DETAB.USR, and it also uses
        the form SETTABST.FRM.  It is built the same way ENTAB is.

    MULTIGREP

        This is an extremely powerful search-and-replace utility.
        It allows you to specify multiple strings to search for and
        replace, and allows you to store sets of search-and-replace
        information to be retrieved and run again.  This can be
        extremely useful in situations where numerous files (source
        files for instance) are identical except for identifiers
        or other tokens that are different.

        HOW TO BUILD IT:  The source is in MULTIGRE.USR, which
        needs to be renamed to USERCODE.BAS, and there are two forms
        it requires, namely FILESAVE.FRM and MULTIGRE.FRM.  As usual,
        just get into VB and add the necessary forms, then build the
        executable.

Here are some more which are so simple they are left as an "exercise
for the reader":

    FILELIST

        This one does nothing but list the files the user selects.  It
        is interesting because, by writing the list to a file, you can
        use that file as file-list input to VB-AWK so as to permanently
        save that set of files as input to other VB-AWK utilities.
        Here's how it's done:  in BeforeAllFiles, set STATUSMESSAGES to
        FALSE.  In BeforeAFile, say "WriteToStatus FILENAME" and change
        BeforeAFile's return value to False, since you're only interested
        in the file's name, not its contents.  Then, run the program,
        click on the Save button from the status box, and you're golden.
        Or, if you can't stand the extra mouse click of saving from
        the status box, just set STATUSFILE to True in BeforeAllFiles,
        and the file list will end up in VB-AWK.LOG.

    DELPROT

        Don't you find it annoying trying to delete protected files?
        To do so from the Windows File Manager takes a protracted
        series of mouse clicks and keystrokes which gets tedious
        quickly. Writing a VB-AWK program to delete whatever protected
        files the user selects takes only two or three lines of code,
        or a few more if you really want to get fancy.  Just make sure
        you set the return value of BeforeAFile to False so it doesn't
        try to read the file after you delete it.

    MAKEBATCH

        VB-AWK is great for generating giant batch files if you still
        deal with DOS on occasion.  Generally, if you have two or three
        DOS operations you need to perform on a bunch of files, it takes
        two or three lines of Visual Basic to write a program that will
        create that batch file for any files you select.


THE COMPANY THAT BRINGS YOU VB-AWK:


                SYNERGY Software & Services, Inc.
                46 Little Brook Rd.
                Wilton, CT 06897
                [phone]
                Compu-Serve: 73467,3661


SYNERGY is a consulting company whose primary purpose is to market
the skills of myself, SYNERGY'S owner and VB-AWK's author, Richard
Robbins.  I have 14 years experience as a professional
programmer, with expertise in C, C++, Visual Basic, Realizer Basic,
Prolog (not that anyone cares about Prolog!), user interface
design, and scientific/engineering programming.  If you have any
needs along these lines, feel free to contact me.


LICENSING AGREEMENT:

VB-AWK is copyrighted software, with all rights reserved by SYNERGY
Software & Services, Inc.  An individual-use license costs 25$,
payable at the end of a 30-day free trial period.  Keeping the
software longer than 30 days indicates acceptance of these terms.

The individual-use license  gives you the right to develop
VB-AWK-based programs for your private, nonprofit use only.  It does
not give you the right to distribute any VB-AWK-based programs
publicly, whether for profit or not.  It does not give you the right
to directly profit from any VB-AWK-based program.  It DOES give you
the right to develop and use VB-AWK-based programs in the course of
your work and on behalf of your clients or customers, and it gives you
the right to distribute a limited number (no more than 10) of copies
of VB-AWK-based programs to your immediate clients or customers, so
long as you do not charge them for it.

If you wish to develop for-profit software based on VB-AWK or
incorporating VB-AWK code, please contact SYNERGY.  You will find our
terms to be extremely reasonable. We have no desire to unfairly limit
competition (unlike Microsoft!), merely the desire to be fairly
rewarded for our efforts.

Your honesty and integrity regarding the licensing agreement for
VB-AWK will enable SYNERGY to continue developing it and other fine
products for the shareware community.  Thank you in advance for your
cooperation.


DISCLAIMER:

In today's litigious age, no product is complete without a
disclaimer, so here's VB-AWK's:  You use VB-AWK entirely at your own
risk.  We think it works great, and the sample programs too, but
nonetheless there could be bugs in it and undoubtedly are.  VB-AWK
carries no warranty of any kind, expressed or implied, and SYNERGY
is not responsible for any damages resulting from any use of VB-AWK.